TPUG - Toronto PET Users Group/TPUG Users Group CD/TPUG Users Group CD.iso/AMIGA/AMICUS/AMIBEST3.ADF/Journal/Journal.DOC

Text File | 1987-07-22 | 19KB | 404 lines

From:  [e-mail] (Davide P. Cervone) Newsgroups:  comp.sources.amiga
Subject:  Journal and Playback (documentation) Date:  10 Jul 87 18:57:20
GMT Reply-To:  [e-mail] (Craig Norborg) Organization:  Purdue
University Computing Center


Well, when I was working on MonIDCMP, I wanted to provide a real-life
example of how it could be used for something useful (like HARDCOPY was to
MONPROC). I thought, "Wouldn't it be great to be able to record and play
back the events that went on in a window?" You could make "Guided Tour"
demonstrations, or turnkey systems that perform all kinds of mouse and
keyboard activity, or you could record the events that demonstrate a bug
that you have been able to produce and send the recorded events to
Commodore as documentation of the bug.

But MonIDCMP doesn't have the power to accomplish this:  it can trick a
window into thinking that things have happened, but gadgets would not
REALLY be pressed, and windows would not REALY be resized.  To do it right
you have to go directly to the Input Device and look at the events that are
being passed to Intuition.

I set out to do this.  What I came up with was JOURNAL and PLAYBACK.  To
see what they do and what they are good for, read the following document,
which describes in detail how to use JOURNAL and PLAYBACK.

With a little more work, these could become important documentation tools
for any Amiga software company.  I am willing to do that additional work,
but only if there is sufficient interest.  If you want to see the
enhancements I discuss below (or any of your own design), please contact me
and let me know.  I did this mainly as an exercise, but think it would be
valuable to continue work on it, but not if I'm the only one who will use
it.

I hope you find these little programs interesting.  I think they're kind of
spooky myself.  I'm not sure I like it when my computer types things for me
without my pressing the keys...

Davide P. Cervone
[e-mail]
[e-mail]
[e-mail]



JOURNAL is a program that records a sequence of mouse and keyboard events
as they occur and stores them in a file.  The file can be played back via
the program PLAYBACK, thus causing the same sequence of events to occur
again.  This is useful for creating demonstrations of programs (much like
the "Guided Tours" on the Macintosh computer).

It also is useful for documenting repeatable bugs:  rather than trying to
describe to Commodore-Amiga Technical Support (or some third-party vender)
what you did that revealed the bug, you could record the actions with
JOURNAL, and send them the output file instead.  Finally, you can use
JOURNAL to set up turnkey demo-disks for conferences and computer shows
that will run unattended while you talk to customers.

It's even possible for PLAYBACK to restart itself when it comes to the end
of the file.  In a future version, there will be a journal editor that
allows you to add "special effects" like explanation windows that tell the
viewer what you are doing, or that call up the narrator device to "speak"
some information as your demonstration progresses.

JOURNAL may not work with some programs the "take over" the system or
bypass the Input.Device (see USAGE NOTES for additional information).


HOW TO USE JOURNAL:

To run JOURNAL, type:

    1> RUN JOURNAL TO <file>

where <file> is the name of the journal file that you wish to produce.
JOURNAL should respond by displaying its version number and telling you how
to cancel it, and by moving the pointer to the upper, left-hand corner of
the screen.  Once the pointer has been moved, JOURNAL will record all the
key presses and mouse movements that you perform, by writing them to the
file that you specified.

This file will be used A LOT, so if it is on floppy-disk, be sure that the
disk can be left in the drive, and that it has enough space available for
the journal file.  The journal grows FAST, so do some exparimenting before
you create a long journal file.  RAM:  is a good place to write small
journals, but may not be appropriate for long ones, as you may need your
RAM space for the programs that you are running.

When you are done creating your journal, press CTRL-LEFTAMIGA-E.  This
signals JOURNAL to stop recording events.  Once you get the "Joural
Complete" message, any further actions will not be added to the journal
file.


HOW JOURNAL WORKS:

JOURNAL installs an input handler into the handler chain of the
Input.Device.  This handler's priority puts it ahead of Intuition, so it
sees the "undigested" events as they arrive from the Keyboard.Device,
Gameport.Device, and Timer.Device.  When keyboard or mouse events are
passed to the handler, it copies them into a linked list of events and
signals JOURNAL that new events are ready, then passes the unmodified event
list on to Intuition.

JOURNAL picks up the list of events and packs them into "TinyEvents" that
take up fewer bytes, and records these in the output file.  To save even
more space in the file, JOURNAL compresses multiple mouse move events into
single output file records when possible, but records the number of events
that were compressed, so that they can be recreated by PLAYBACK, if
desired.  The amount of compression is controlled by command-line options
(see below).

When the handler sees that CTRL-AMIGA-E has been pressed, it signals
JOURNAL, which tells the Input.Device to remove the handler from the chain
and closes the journal file.


JOURNAL OPTIONS:

JOURNAL supports a number of command-line options that modify its behavior:

TO <file>     Designates <file> as the JOURNAL output file (the keyword
                "TO" is optional).

DX x            Specifies the amount of x movement that can be compressed
        into one output event (mouse movements are added together
        until their combined x-offsets exceed DX or their
        combined y-offsets exceed DY). The default value is 8.

    DY y            Specifies the amount of y movement that can be compressed
                    into one output event (mouse movements are added together
                    until their conbined x-offsets exceed DX or their
                    combined y-offsets exceed DY).  The default value is 8.

    SMOOTHX x       Specifies an alternate value for DX that is used when
                extra precision is needed (for example, when you need
            to draw a free-form line in a paint program).  This
            value is in effect when the SMOOTH and TRIGGER mask
            conditions are met (see below).  The default value is 1.

    SMOOTHY y       Specifies an alternate value for DY that is used when
                    extra precision is needed (for example, when you need
                    to draw a free-form line in a paint program). This
                    value is in effect when the SMOOTH and TRIGGER mask
                    conditions are met (see below). The default value is 1.

    SMOOTH mask     Indicates which qualifier keys MUST be pressed in order
                    to activate the SMOOTHX and SMOOTHY values.  Whan ALL
                    the keys specified by the SMOOTH mask are pressed, and
                    AT LEAST ONE of the keys designated by the TRIGGER mask
                    is pressed, then the SMOOTHX and SMOOTHY values are
                    used in place of DX and DY.  By default, the left Amiga
                    key specifies smoothing.

    TRIGGER mask    Indicates which qualifier keys trigger the use of SMOOTHX
                    and SMOOTHY.  When ANY ONE of the keys indicated by
                    TRIGGER mask is pressed, and ALL of the keys specified
                    by the SMOOTH mask are pressed, then SMOOTHX and
                    SMOOTHY are used in place of DX and DY.  By default,
                    any qualifier key triggers smoothing.

For people who understand "C" syntax, the expression that determines
whether to use DX and DY or SMOOTHX and SMOOTHY is the following:

  if (((Qualifiers & SmoothMask) == SmoothMask)
       && (Qualifiers & TriggerMask))
    use SMOOTHX and SMOOTHY
   else
    use DX and DY

Note that this provides considerable flexibility in specifying what will
activate smoothing.  For example, to specify that pressing either button
will cause smoothing, use:

    1> JOURNAL TO <file> SMOOTH 0 TRIGGER 0x6000

To specify that left Amiga plus left shift together with either button
should cause smoothing, use:

    1> JOURNAL TO <file> SMOOTH 0x0041 TRIGGER 0x6000

The complete set of qualifier values is listed in the include file
"DEVICES/INPUTEVENT.H".  Important values are listed here:

    Left Shift          0x0001
    Right Shift         0x0002
    Caps Lock           0x0004
    Control             0x0008
    Left ALT            0x0010
    Right ALT           0x0020
    Left Amiga          0x0040
    Right Amiga         0x0080
    Left Button         0x2000
    Right Button        0x4000

To determine the mask value, take the bitwise OR of the values for the
qualifiers you want to use.  Note that the SMOOTH and TRIGGER masks should
be specified in HEX, not decimal.


HOW TO USE PLAYABCK:

To use playback, type:

    1> RUN PLAYBACK FROM <file>

where <file> is the name of a journal file recorded with the JOURNAL
command.  PLAYBACK should print a message telling you its version number
and how to abort the playback, and then should begin playing back the
recorded events.  All you have to do is sit back and watch.

When PLAYBACK is running, you will not be able to control the mouse
yourself, and the keyboard will have no effect (except for CTRL-C, which
cancels PLAYBACK). This is so that you do not disturb the sequence of the
journal being played back.

When the last event is played back, PLAYBACK will inform you that it is
done.

To cancel PLAYBACK at any time, press CTRL-C.  This is the only key that
has any effect while PLAYBACK is running.


HOW PLAYBACK WORKS:

PLAYBACK installs an input handler into the handler chain of the
Input.Device.  This handler's priority puts it ahead of Intuition, so it
can insert new events into or remove events from the stream seen by
Intuition.  PLAYBACK reads packed events from the journal file and unpacks
them into an event buffer where the input handler adds them to the event
stream.

Since multiple
mouse movements are compressed into single journal records, PLAYBACK must
uncompress these by extrapolating intermediate mouse positions.  The input
handler removes all keyboard and mouse events sent to it by the Input.Device
so that these do not interfere with the journal being played back.  If the
handler sees a CTRL-C it signals PLAYBACK that the user wants to abort the
playback before it is complete.  PLAYBACK then requests the input.Device to
remove the handler.

PLAYBACK uses a FIFO event queue to supply events to the input handler.
Since the handler may have to wait for some time to pass before it posts
the next event in the queue, this allows PLAYBACK to "read ahead" in the
journal file, and prepare additional events for posting.  This makes the
mouse movements smooth and un-interrupted.  When PLAYBACK fills the queue,
it waits for the handler to post some events (freeing space in the queue).
You can control the size of the queue via the EVENTS command-line option.


PLAYBACK OPTIONS:

PLAYBACK supports a number of command-line options that modify its behavior:

    FROM <file>     Specifies the journal file to be played back (the keyword
                    "FROM" is optional).

    EVENTS n     Specifies the size (in events) of the events buffer used to
                    pass events from PLAYBACK to the input handler.  EVENTS
                    must be at least two.  The default value is 50, but it
                    can be set as low as 10 and still provide acceptable
                    performance for some tasks.  The number of events may
                    need to be increased if you have many other tasks
                    running, or are accessing the disk containing the
                    journal file frequently, or have specified small DX and
                    DY values when you recorded the journal file.

    SMOOTH          Specifies that compressed mouse moves should be expanded
                    into multiple mouse moves of smaller offsets.  This makes
                    the playback look smoother, and makes precise mouse moves
                    possible without taking up space in the journal file.
                    The default is SMOOTH.

    NOSMOOTH        Specifies that compressed mouse moves should be left
                    compressed (i.e., no extrapolated events should be
                    posted). This may be necessary if you need extremely
                    quick response time or if you have specified a small DX
                    and DY during recording and do not need to uncompress
                    mouse moves.  The default is SMOOTH.


HOW TO COMPILE AND LINK JOURNAL AND PLAYBACK:

JOURNAL AND PLAYBACK were developed using the Lattice C compiler version
3.10. I have tried to make it as generic as possible, but since I don't
have the Aztex C compiler, I don't know whether it works with Manx.  For
Lattice C, all you have to do is:

    1> lc -v journal playback
    1> asm handlerstub
    1> blink with journal.lnk
    1> blink with playback.lnk

The '-v' option is so that no stack checking code will be produced.  Since
the input handler runs on the Input.Device's stack, this would confuse the
stack check code and probably crash the system (I never tried it, though).


USAGE NOTES:

Since PLAYBACK plays back exactly what was recorded by JOURNAL, it is
important that the initial conditions be the same for both JOURNAL and
PLAYBACK.  If even one window is not where it was when your ran JOURNAL,
then PLAYBACK may become hopelessly out of synchronization.

It is best to run JOURNAL from a freshly booted system, or a newly opened
NewCLI or AmigaDOS window.  If the journal needs programs or other windows
to be open, don't open them first and then run JOURNAL.  Instead, run
JOURNAL and then open the windows or run the programs.  This way you can be
sure that what you want will be there, and in the proper places.  If you
are recording actions on the Workbench, you should start with all the disk
windows closed, and the disks in their default positions then open them
within the journal.  Beware that disk positions may change depending on the
order in which they were inserted.

One "feature" of JOURNAL and PLAYBACK is that they do not know about disk
insert requesters.  If a disk requester comes up, JOURNAL keeps right on
recording mouse moves and key strokes.  If you cancel the requester, so
will PLAYBACK.  But if you put in a disk and the requester goes away, there
is no guarantee that the user who is playing back your journal will replace
the disk in the same amount of time you did (in fact, he may never replace
it), so the rest of the journal may become out-of-synch.

Worse yet, the user can pop a disk out of the drive at any time, which may
cause a disk requester to come up that did not appear when you recorded the
journal, or the user might have fewer disk drives than you do, so he may
have to swap drives differently from how you did.  All of these cases cause
trouble for JOURNAL and PLAYBACK, so be careful when you are using multiple
disks with journal. (See FUTURES for additional comments on
disk-requesters).

Since JOURNAL will be writing lots of data to its output file, and PLAYBACK
will be reading losts of data from the journal file, the journal file must
be on a disk that can remain in a drive.  RAM:  is a good candidate for
small journals, but may not have room for a large journal plus the programs
that will be running.

JOURNAL's input handler allocates memory for the events as it copies them.
This memory is not freed again until JOURNAL actually records the event.
If events are coming in very fast, JOURNAL may not be able to keep up with
them.  This may use up considerable memory until JOURNAL can catch up.  If
you are having memory problems while using JOURNAL, try slowing down your
mouse movements to give JOURNAL some time to catch up.

You may need to run JOURNAL and PLAYBACK at higher priorities than your
normal processes in order to give them enough time to get the events to and
from the input handler in a timely fashion.  Both progams use the Wait()
function and neither "busy waits," so they should cooperate with other
tasks even when they are at a higher priority.

If your journal runs a program that has to be loaded from disk, be sure to
wait long enough for it to be loaded during the PLAYBACK.  Some disks take
longer than others, and sometimes there are slight timing differences
between JOURNAL and PLAYBACK.  Give a little extra time after disk accesses
before you move the mouse or press a key.

JOURNAL only records mouse and keyboard events that come through the input
device.  It does NOT record events that are received directly by a program
through a message port from devices opened explicitly by the program.  For
example, if your program opens the timer device and gets timer messages,
these are NOT recorded by JOURNAL.  Similarly, JOURNAL does not record
messages from the serial port, parallel port, or second mouse port.  Note
that this means that JOURNAL will not record joystick motions from the
second mouse port, so PLAYBACK can not reproduce them.  This may make it
impossible to make a journal record of some games.


FUTURES:

The disk insert problem mentioned in USAGE NOTES above needs to be fixed.
The only solution I can think of is to use SetFunction to replace
AutoRequest with a function that signals the JOURNAL or PLAYBACK process
that a request has occured, then calls the original AutoRequest, then
signals when the request is finished.  JOURNAL and PLAYBACK would "pause"
until the AutoRequest was done, and then continue recording or playing
back.  Since AutoRequest allows you to specify what kinds of flags will
cancel the request, the replacement routine could check these to see if
DISKINSERTED messages will satisfy it.  If not, then the original
AutoRequest could be called without signalling the JOURNAL or PLAYBACK
processes.  This way we would not be trapping the wrong requesters.
Unfortunately, Workbench disk requests do not seem to use the DISKINSERTED
flag, so something more sophsticated may be needed.  I am open to
suggestions.

In the future (if there is enough interest), I plan to write a journal
editor that allows you to step through a recorded journal and modify it by
changing the events, adding new events, or deleting events.  Also, you will
be able to add "special effects" like pop-up windows that contain
explanations of what your program is doing, what qualifier keys are being
pressed, etc.  I also hope to allow you to do this via the narrator device
rather than through a window, if desired.  If I get real ambitious, I might
even add something to play music from a file, but that will have to be far
future for now.  If you want these features, please let me know.


AUTHOR:

Davide P. Cervone
University of Rochester Computing Center        [e-mail]
Taylor Hall                                     [e-mail]
Rochester, New York  14627                      [e-mail]
[phone]